en | Troubleshooting
Complete the getting started tutorial first if you can: http://tutorial.keefox.org
Pay special attention to any troubleshooting advice displayed at the top of the page. At the very least it should give you a clue about the type of problem that is preventing KeeFox from behaving the way you expect.
Once the basics are working, reading the contents of the tutorial will ensure you're up-to-date with the basic features of KeeFox version 1.5 (it has been significantly improved in 2015).
If you have just upgraded to KeeFox 1.5, you might want to review the extra detail on the Upgrading from KeeFox 1.4 page.
- KeeFox panel has an "Install KeeFox" button
- KeeFox panel has a "Launch KeePass" button
- I have to enter a password every time I load KeeFox
- KeePassRPC is already listening for connections
- Troubleshooting tips when a particular website does not get its login form filled in automatically:
- KeeFox asks me to save a password for a site that already has a password entry
- KeePass tells me that the plugin could not be loaded
- Debug the problem
- Certificate problems
- KeePassRPC plugin does not load (no error message is displayed)
This suggests that KeeFox has been unable to automatically setup on your system.
First, try to find the setup page. KeeFox loads an orange setup page when it is first installed - this page helps you to easily setup the link between KeeFox and KeePass. Occasionally other Firefox add-ons or unusual configurations might prevent KeeFox from loading this page. It's possible that the page has been loaded in a different tab, in a different window or in a different tab group so have a good look around.
If you can't find the setup page try loading it directly by pasting one of the following URLs into your address/location bar:
- chrome://keefox/content/install.xul (for initial KeeFox setup on Microsoft Windows)
- chrome://keefox/content/install.xul?upgrade=1 (for upgrading KeeFox on Microsoft Windows)
- chrome://keefox/content/install_mono.xul (for initial KeeFox setup on Linux or Mac)
- chrome://keefox/content/install_mono.xul?upgrade=1 (for upgrading KeeFox on Linux or Mac)
If the setup page doesn't work for some reason, any error message displayed on the page might help but if not you'll probably want to read about how to perform a manual setup. It's fairly straight forward but not as easy and quick as the automatic setup so if you manage to get KeeFox setup and working using the manual method, any tips you can post on the forum to help us understand what situations require a manual setup would be appreciated.
KeeFox thinks that the basic setup steps have been completed but occasionally it will be unable to detect a problem with an upgrade from an earlier version of KeeFox. So the first thing to do is check that the KeePassRPC plugin is actually installed in KeePass > Tools menu > Plugins. Secondly, check that the version of KeePassRPC is correct in the Plugins dialog. If in doubt, try the appropriate "chrome://...upgrade=1" links in the above section and re-run the setup process (on Windows) or follow the manual instructions.
There could be other problems preventing communication between Firefox and KeePass. Some common things to look at include:
- Other security software such as anti-virus or firewall (KeeFox communicates on TCP port 12536 and 12546 by default).
- Sophos Anti-virus is an example of a consistently badly behaved piece of software in this regard.
- Try white-listing 127.0.0.1 and localhost in your security software settings (ask them for help if you're not sure how to do this).
- Other Firefox add-ons, KeePass plugins or ad blockers. A small list of examples that are known to cause problems:
- RequestPolicy - This CSRF protection add-on has a bug that causes it to think that the connection from KeeFox to KeePass is a cross-site request that should be blocked. Until the RequestPolicy devs resolve the problem, it's easy to workaround by adding a rule to always allow traffic to 127.0.0.1:12546
- FoxyProxy (and maybe other proxy add-ons) - When this addon is configured to proxy all Firefox traffic through a specific proxy server, KeeFox connections to KeePass will also be affected. It should be possible to configure FoxyProxy rules to avoid this but that's beyond the scope of this manual. Alternatively, other proxy add-ons may allow all remote traffic to go through a remote proxy while leaving the local traffic untouched.
- Ad Muncher - This system-wide ad blocker has a bug that breaks web sockets on your system (increasingly, you will find more websites and applications fail while using this software).
- KeePassHTTP - No reported problems in KeeFox 1.3+ yet but there are some unverified issues with earlier versions.
- Privacy Badger - May get a false positive from KeeFox and block 127.0.0.1 after a while. Can be fixed by going to privacy badger settings and manually setting 127.0.0.1 to Allowed.
- Is Firefox configured to use a proxy? Make sure that it is not sending local network traffic to the remote proxy. For example, the Windows proxy settings have an option to "Bypass proxy server for local addresses" - make sure that option is enabled.
- Are you running more than one instance of KeePass or have other people that share your computer got KeePass open at the same time? If you are using a KeeFox version lower than 1.3, also see the "KeePassRPC is already listening for connections" section below.
- Make sure that you have exactly one KeePassRPC.plgx file in your KeePass program folder. KeeFox installs the plugin to a subfolder called "plugins" but KeePass will load any plugin it finds in either its own folder or any subfolder. So if you have manually tweaked the KeePass program folder or made a backup of the plgx file you might have more than one KeePassRPC plugin installed, possibly an older version.
- Check if your network hosts file is correctly configured to send localhost traffic to your local 127.0.0.1 IP address
- If you're still stuck and want to gather some more information to help you or someone else diagnose the problem, you could try running this JSFiddle to test if your local Firefox is able to connect to KeePass: http://jsfiddle.net/awDLc/125/
When testing, be aware that some applications / add-ons will only prevent the initial connection from KeeFox to KeePass. For example, forcing all localhost traffic through an external proxy using a tool like FoxyProxy will not cause any problem provided that you have already established a connection between Firefox and KeePass (until you close one of those applications). This could be a useful way to work around some problems until third parties resolve the problem at their end, but it could also lead to confusing results if you're not careful when trying to narrow down the cause of your connection problem!
Naturally, there are a lot of passwords involved with a password manager so first let's be clear what password you're being asked to enter.
This type of password should appear if you're installing KeeFox for the first time, it's been a long time since you first installed it or you have just upgraded from KeeFox 1.2.x or earlier. You'll be asked to type a random password from a KeePass dialog box into one displayed by Firefox. There are more details and screenshots in the upgrade notes.
If you keep being asked to enter this random password it could be caused by any of the following:
- You have some other add-on or setting which prevents Firefox from saving the KeeFox authorisation key.
- For example, the PassIFox addon is known to disable Firefox's internal security protection so features like Firefox Sync and addons like KeeFox will not work while PassIFox is installed.
- You have set KeeFox (and KeePassRPC) to the high security level
- You have set a very short expiry time for the authorisation
- Maybe some other reasons we've not come across yet (such as problems with Firefox or KeePass being unable to save their configuration files?)
- Firefox 41 and lower only: You are using the default (medium) security level and tell Firefox to delete all password data when exiting Firefox. You can check and disable this (unnecessary) option in the main Firefox Options Privacy panel; click on the "Settings" button associated with the custom configuration for "Clear history when Firefox closes"; uncheck the "saved passwords" option.
The Firefox/Thunderbird master password dialog box (sometimes mentioning the "Software security device") is part of Firefox but it can be indirectly displayed by KeeFox. You can read more about the master password here and find out how to reset it here (if you do reset it, you'll have to re-authorise the KeeFox connection to KeePass afterwards).
It can be a bit confusing that KeeFox triggers the appearance of this password dialog box because you may have previously associated it with the built-in Firefox password manager. There is more technical detail here but the gist of it is that when you authorise a new connection to KeePass the secret key has to be stored somewhere so that it can be re-used when KeeFox next connects to KeePass.
To allow you to optionally protect this key from specialised malware on your system we store it in the same password store that Firefox would store your usernames and passwords for websites if you used the built-in Firefox password manager. Many people won't need the extra protection of the master password but it's an optional extra layer of security against specialised malware so worth considering alongside your other security protection.
It's probably unnecessary to mention the KeePass master key dialog but let's cover it for completeness. This dialog is presented by the KeePass password manager, you would have it even without KeeFox installed and it is the main password you need to enter in order to access all the other passwords stored within your KeePass database. There are KeePass options you can set to adjust how frequently you need to enter this password but that's beyond the scope of this manual - check out the support resources at http://keepass.info for more information.
If you're asked for any other passwords, they will be from websites you visit or other browser add-ons. Look for any websites that are set to load every time you start Firefox and try disabling other add-ons if you can't pin down the cause.
If you see this error message when you start KeePass, KeeFox will be unable to connect to KeePass to access your passwords.
These are the most likely explanations in decreasing order of likelihood:
-
You already have a version of KeePass running.
-
Someone else logged into your computer and already has a version of KeePass running.
-
A different application on your machine is using one of the ports KeePassRPC requires (12536 and 12546)
-
Plugin files required by KeeFox aren't properly installed. Before you try to run KeePass again, verify that you have copied
KeePassRPC.plgxinto a subfolder namedpluginswhich you have placed inside the KeePass application directory.For example: if your KeePass application directory is named
/home/bob/KeePass, then putKeePassRPC.plgxinto a subfolder named/home/bob/KeePass/plugins/. For the list of common locations for the KeePass application directory, visit their configuration files help page.
To help diagnose the cause of the error, you may want to use the Windows 7 resource monitor tool's "network" tab or equivalent monitoring tools on your operating system.
If you need to run more than one instance of KeePass (such as for multiple users on the same machine), you'll need to configure each pair of KeePass and Firefox to use a different port.
KeeFox < 1.3: This error message is new in KeeFox 1.3 but the same problem could occur in earlier versions - the only symptom is that the KeePassRPC plugin does not load - see the section below for ways to debug the problem to verify if it is related to the issues that cause this error message to appear in KeeFox 1.3 and above.
-
Check that your KeePass entry is configured correctly. If in doubt, it is often easiest to log in to the site manually and get KeeFox to update the password or even save the password as a new entry.
-
Some websites use JavaScript to prevent automated form fillers from submitting your password to them. In some cases they provide an accessible alternative login page (they are required to do so by law in most countries). If you find this alternative login page you may be able to tell KeeFox to submit to the login form on that page rather than the usual JavaScript login form. Try disabling JavaScript or try submitting incorrect data to the form in order to reveal the URL of the accessible login form.
-
If you can't get the automatic behaviour to work, you can always use the "copy username/password" feature available on each login in the KeeFox panel (requires KeeFox 1.5+).
-
If all else fails, you should learn how to use the KeePass auto-type feature. This simulates the typing of keys on your keyboard so with appropriate use of tabs, spaces and other characters you may be able to submit a login through that method.
Please do let us know on the forum when you find sites that don't work. We'll definitely take a look into it and see if we can improve KeeFox in the future so that it works with even more sites. Unfortunately, we may not always be able to respond to each individual report.
This indicates that there is something different about that password that was submitted compared to the one that you have stored in KeePass. Sometimes it is a visible difference such as whether or not a "remember me on this computer" checkbox is ticked. Other times it can be invisible such as a hidden random number that the website includes with every form submission. There may also be a bug in KeeFox which means that entries filled in via the use of an alternative URL could be seen as different because they do not have the same primary URL (I'll try to verify this soon and improve it sometime in 2015).
When the KeePassRPC plugin does not get loaded correctly, there can be a variety of reasons, most of which will require you to upgrade (or sometimes downgrade) one or more of the components on your system.
There are no known reasons for this problem if you are using the latest version of KeeFox and KeePass (and Windows Vista or newer).
If you do suffer from the problem, it is probably due to a corruption in your Windows installation (sometimes specifically the Microsoft .NET windows component) so repairing Windows and/or reinstalling the .NET Framework might help. These problems are often caused by malware so make sure you thoroughly test for and eridicate any viruses, spyware, etc.
If that doesn't help, you'll need to follow the guidelines in the Debug the problem section and report your findings on the support forum or in an issue here on github.
There are dozens of bugs that affect Mono and KeePass on these platforms. Unfortunately it is not even as straight forward as just installing the latest versions since Mono has a tendency to create new problems when it fixes old ones.
We try to work around as many bugs as possible and most stable versions of KeeFox will work just fine with the versions of Mono and KeePass that were available at the time of the KeeFox release. Getting an old version of KeeFox to work with a new version of KeePass and Mono (or vice versa) may be problematic.
Please make sure you have read the information on this wiki about running KeeFox on Linux/Mono.
If the above tips don't help, you can run KeePass from the command line / terminal with some extra parameters to enable some debug logging which may be useful to diagnose the problem (if you don't understand the output, you can post it for others to help with).
The following are the most useful:
--debug : This puts KeePass into debug mode. Sometimes this provides useful information but often it just outputs a generic and meaningless message.
--saveplgxcr : Note: starting with KeePass 2.31, this option was removed - use --debug instead. In previous versions of KeePass 2.x, this made KeePass output detailed information about why it was unable to build the plugin. KeePass will tell you where to find the file with the output.
--KPRPCDebug= : Output KeePassRPC plugin debug information to a location of your choosing. E.g.: --KPRPCDebug=c:\temp\kprpc-debug.log
This section only applies to KeeFox < 1.3: If you have tried all the basic troubleshooting tips and still can't get KeeFox to see that KeePass is running, your Windows certificate store may require some maintenance. This seems to happen most frequently when moving accounts between computers or reinstalling windows.
The KeePassRPC plugin that KeeFox uses to communicate with KeePass automatically generates a security certificate which it uses to encrypt the communication between KeePass and KeeFox. If this certificate becomes invalid for any reason or does not match what KeePassRPC and KeeFox are expecting you will need to delete the certificate and reinstall KeeFox (so that it creates a new one).
Type "mmc.exe certmgr.msc" into the Windows 7 start menu (http://msdn.microsoft.com/en-us/library/ms788967.aspx has more detailed instructions). Then select the "Personal" group and the "Certificates" subgroup. In the main panel you need to delete the "KeePassRPC certificate for xyz" (where xyz is related to your computer name). Now reinstall KeeFox and go through the setup process to reestablish the secure connection to KeePass.
Further tips can be found by searching in the forum http://keefox.org/help/forum (and feel free to post your own tips here).
If you are sure that the KeePassRPC.plgx file is in the correct location, there could be a rare problem preventing the plugin from being loaded by KeePass.
The most likely cause is that the plugin is already running elsewhere on the computer.
Using the "--KPRPCDebug" debug command line option can output more information about the problem to a location of your choosing. E.g.:
--KPRPCDebug=c:\temp\kprpc-debug.log